Manipulating Print File Objects(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 4 - Advanced Printing Features / Using Advanced Printing Features

Manipulating Print File Objects
Print files can only be created by printing, which causes the document to be spooled to the file. A portable digital document is a print file created by the user printing to a PDD Maker GX desktop printer.
After you create a print file, your application or another application can manipulate it. QuickDraw GX allows your application to

open and close a print file
save a print file
retrieve a job object associated with a print file
retrieve page or page format data from a print file
count the pages in a print file
delete, replace, or insert pages

Opening and Closing a Print File
You use the GXOpenPrintFile function to open a print file and use the GXClosePrintFile function to close one. You must provide a job object when you open the print file. You can dispose of the job object after the file is closed.
Listing 4-8 shows how to open and close a print file. It also shows how to determine the number of pages in a print file with the GXCountPrintFilePages function.
Listing 4-8 Opening and closing a print file
OSErr MyGetPrintFilePages(FSSpec *printFSSpec, long *numCopies)
{
   OSErr       err;
   gxPrintFile thePrintFile;
   gxJob       fileJob;

   /* 
      Create a new job object for GXOpenPrintFile, open the print 
      file object, get the number of pages in it, close it, and 
      check for errors. Finally, dispose of the temporary job 
      object and return. 
   */
   err = GXNewJob(&fileJob);
   if (err == noErr)
   {
      thePrintFile = GXOpenPrintFile(fileJob, printFSSpec, 
                                                      fsCurPerm);
      *numCopies = GXCountPrintFilePages(thePrintFile);
      GXClosePrintFile(thePrintFile);

      err = GXGetJobError(fileJob);
      GXDisposeJob(fileJob);
   }
   
   return err;
}
Saving a Print File
You use the GXSavePrintFile function to save a print file. You should save a print file after you have added, deleted, or modified its pages, formats, or job object information.

Obtaining the Job Object for a Print File
You use the GXGetPrintFileJob function to obtain the job object associated with a particular print file object. This function is useful for determining which job object was associated with the print file when the file was opened by the GXOpenPrintFile function, if the reference to the job object was not saved.

Reading Print File Data
You use the GXReadPrintFilePage function to retrieve a page from a print file along with its page format. The page is returned as a single picture shape, which is how it is stored in the file, even if the page was created with several calls to GXDrawShape.
When you call GXReadPrintFilePage, you must specify the page number for the page, starting from 1. You must also specify which view ports you want the picture shape to refer to, so that the shape can be drawn through them when it is displayed onscreen. Listing 4-9 shows how to read a page from a print file.
Listing 4-9 Reading a page from a print file
OSErr MyReadPrintFilePage(MyDocumentPtr myDocument, FSSpec 
                           *printFSSpec, long whichPg, 
                           gxFormat *pgFormat, gxShape *pgShape)
{
   gxPrintFile    thePrintFile;

   /* 
      Open the print file object, read the page, close the file,
      and check for errors.
   */
   thePrintFile = GXOpenPrintFile(myDocument->documentJob, 
                                    printFSSpec, fsCurPerm);
   GXReadPrintFilePage(thePrintFile, whichPg, 1, 
               &myDocument->documentViewPort, pgFormat, pgShape);
   GXClosePrintFile(thePrintFile);

   return GXGetJobError(myDocument->documentJob);
}
Counting the Pages in a Print File
You use the GXCountPrintFilePages function to count the number of pages in the print file object that you specify. See Listing 4-8 on page 4-29 for an example.

Adding or Deleting Print File Pages
After the user prints a file, you can replace, delete, or insert pages. You use the GXReplacePrintFilePage function to replace a single page from a print file. You can use the GXDeletePrintFilePageRange function to delete a range of pages within a specified print file. You can use the GXInsertPrintFilePage function to insert a page in a print file. For changes to the print file to take effect permanently, you must call GXSavePrintFile before you call GXClosePrintFile.